Comments should be sent to AppleLink address OPENTPT or Internet address 'opentpt@applelink.apple.com' Unfortunately, we can not provide general technical support via this AppleLink address. Technical support questions should be directed to AppleLink address DEVSUPPORT or Internet address 'devsupport@applelink.apple.com'.
Overview
This is a development release of Open Transport for AppleTalk and TCP/IP.
This release includes an AppleTalk Phase 2 stack containing PAP, ADSP, ATP, DDP and below. It includes a TCP/IP stack containing TCP, UDP, IP and a DNR. More information on the particular capabilities of these two stacks are contained in documentation specific to AppleTalk or TCP/IP (see below).
What this release contains
This release includes
• an Installer that will install Open Transport 1.1b6 and Apple Shared Library Manager 2.0 onto your machine.
• a Developer Files folder that contains:
• An ASLM Developer folder contain tools for developing ASLM shared libraries, as well as debugging versions of the Shared Library Manager itself.
• An Open Tpt Client Developer folder that contains documents, header files, MPW libraries, and sample programs
WARNINGS
See also the ReadMe file that accompanies Open Transport
• If you have installed the debug version of OpenTransport on a NuBus Power Macintosh, you will ALWAYS get 2 UserBreaks when booting your machine. The first UserBreak will have no text associated with it, while the second will have the text "TLibrary::PrivateLoadSegment- Loading a Segment failed". Please do not report these as bugs.
Development Information
This developer kit was created using the pre-release MPW environment from E.T.O. #18
IMPORTANT DEVELOPER WARNING!!!
The 68K libraries for version 1.1b1 through 1.1b5 were incompatible with the libraries from the 1.0.6/1.0.7 Open Transport releases. Because some developers have released 68K products with the libraries of these releases, it has been decided that we should modify the 1.1 68K libraries to insure compatibility with the those libraries. Because of this, any 68K code linked with the 1.1b1 through 1.1b5 libraries will not be compatible with the final 1.1 Open Transport product. The libraries with the 1.1b6 release are compatible with the library from the 1.0.6/1.0.7 Open Transport releases, and will be compatible with the final 1.1 Open Transport product.
Linking with Open Transport Libraries:
For 68K Libraries:
You should link with OpenTptUtils.o (for model far) or OpenTptUtils.n.o (for model near) if you are writing code that is only dealing with ports. Linking with this file keeps the whole Open Transport environment from loading.
If you're not sure, try linking with this file. If you get unresolved symbols, then link with OpenTransport.o.
If you are writing an application, also link with OpenTransportApp.o (for model far) or OpenTransportApp.n.o (for model near). If you are writing a stand-alone code resource, CFM fragment, or ASLM shared library, also link with OpenTransportExtn.o (for model far) or OpenTransportExtn.n.o (for model near).
You should link with OpenTransport.o (for model far) or OpenTransport.n.o (for model near) if you are writing code that creates and uses endpoints, mappers or other providers. If you are writing an application, also link with OpenTransportApp.o (for model far) or OpenTransportApp.n.o (for model near). If you are writing a stand-alone code resource, CFM fragment, or ASLM shared library, also link with OpenTransportExtn.o (for model far) or OpenTransportExtn.n.o (for model near).
You should link with OpenTptATalk.o (for model far) or OpenTptATalk.n.o (for model near) if you are writing code that uses the AppleTalkServices provider.
You should link with OpenTptInet.o (for model far) or OpenTptInet.n.o (for model near) if you are writing code that uses the InternetServices provider.
In all cases, if you are NOT writing an appliction, but are writing a stand-alone code resource, CFM fragment, or ASLM shared library, also link with OpenTransportApp.o (for model far) or OpenTransportExtn.n.o (for model near).
If you are writing code that uses ASLM, then you should link with the ASLM libraries first, then the Open Transport libraries, ignoring any duplicate symbol definitions that occur between them.
For PPC Libraries:
You should link with OpenTransportUtilLib and OpenTptUtilsPPC.o if you are writing code that is only dealing with ports.
Linking with this file keeps the whole Open Transport environment from loading. If you're not sure, try linking with this file.
If you get unresolved symbols, then link with OpenTransportLib and OpenTransportPPC.o.
If you are writing an application, also link with OpenTptUtilsAppPPC.o. If you are writing a stand-alone code resource, CFM fragment, or ASLM shared library, link with OpenTptUtilsExtnPPC.o instead of OpenTptUtilsAppPPC.o.
You should link with OpenTransportLib and OpenTransportPPC.o if you are writing code that creates and uses endpoints, mappers, or other providers.
If you are writing an application, also link with OpenTransportAppPPC.o. If you are writing a stand-alone code resource, CFM fragment, or ASLM shared library, link with OpenTransportExtnPPC.o instead of OpenTransportAppPPC.o.
You should link with OpenTptATalkPPC.o and OpenTptAppleTalkLib if you are writing code that uses the AppleTalkServices provider, or AppleTalk utility routines
You should link with OpenTptInetPPC.o and OpenTptInternetLib if you are writing code that uses the InternetServices provider, or TCP/IP utility routines.
If you are writing code that uses ASLM, then you should link with the ASLM libraries first, then the Open Transport libraries, ignoring any duplicate symbol definitions that occur between them.
Known bugs/incompatibilities
• The settings "Load only when needed" has been disabled for AppleTalk. It is not technically feasible at this time.
• OTScheduleDeferredTask only runs tasks when the Open Transport environment is about to become quiescent. This causes clients using it not to run very often.
• When using MacPPP, please delete all unused version of the Control Panel (ConfigPPP), extension (PPP), and preferences. Opening ConfigPPP may crash your system if it finds inappropriate PPP resources.
• When running TCP/IP over a SLIP or PPP link only, it is recommended that you leave the "Router address" and "Subnet mask" fields blank in the TCP/IP Control Panel. Since the values assigned to these by some Internet providers may in some circumstances be incompatible with Open Transport TCP/IP, Open Transport will automatically generate a default router address and subnet mask when using either a SLIP or a PPP Link if you leave these fields blank.
API changes since 1.0.5b3
• Added a generic DNR Query API for TCP/IP.
• Added the OTGetProviderPortRef API
• Added the OTTransferProviderOwnership API
• An 'otvr' Gestalt selector was added that returns the version of Open Transport in the standard 4-byte 'vers'-1 format.
• OPT_SRL_xxxxxx names for serial options were changed to OPT_SERIAL_xxxxxx
• kOTInvalidConfigurationPtr and kOTNoMemoryConfigurationPtr defines were added.
• Fixed the prototype for OTATomicAdd32 for 68K code - it was prototyped to return a Boolean, and it should have been an SInt32.
Bug Fixes since 1.0.5b3
General
• Under certain conditions, T_GODATA and T_GOEXDATA events were received and cleared by Open Transport. This resulted in a kOTLookErr being returned to the client, but the events were already cleared.
• Synchronous Listen() calls no longer hang.
• Fixed a problem where 0-length receive calls lost the rest of the data
• Metrowerks sample projects now have their resources intact, so they should be usable now.
• Fixed a problem where callbacks to registered 68K clients did not have their A5 world set up.
• On PowerPC, Open Transport now swaps the stack when calling routines that might "blow up" the foreground applications stack.
• Fixed some problems with OTCreateOptionString when the option was a kOTPrintableString.
• Fixed a write to NULL that occurred when loading a driver for the first time.
• Fixed a bug in the various time stamp routines, where the timestamp returned on 603 and 604 processors was incorrect (OK, the lower 40 bits were correct, but the upper 24 were not).
• The routine OTTransferOwnershipPriv was exported to keep the Metrowerks linker happy.
Backward-compatibility for AppleTalk
• If a port is locked in the AppleTalk control panel, AppleTalk compatibility will not automatically switch to LocalTalk if the port does not exist or if it's driver cannot be initialized. Instead, AppleTalk will remain Off. A notification was added to inform the user that this has occurred.
• Fixed a crash at Shutdown or Restart if the shutdown or restart was done and a packet arrived from the network at an inconvenient time (most often if a file server was still mounted).
• Fixed a memory leak whenever opening a DDP socket failed.
• On NBP Lookups, the enumerator value is now the correct enumerator value, instead of a value made up by the backward-compatibility code. This allows some network management programs to function better.
AppleTalk
• May bugs were fixed in the PAP implementation. It still needs some work, but it can now print properly to Apple Laserwriters.
• Fixed a problem in PAP where the OPT_SERVER_STATUS option was returning garbage if the endpoint was not a "listening" endpoint.
Backward-compatibility for TCP/IP
• Fixed a problem where accepting an incoming connection could result in a crash if an error occurred.
• Fixed a problem with Fetch crashing when putting a Text file.
TCP/IP
• Fixed a problem where passing a dot-format IP address to SysInfo or MXInfo would hang the system
Links
Changes since 1.0.5b3
General
• OTDestroyDeferredTask will no longer return a kEAGAINErr. It always succeeds.
• The OTGetTimeStamp function has been made native on PowerPC. It no longer uses the Microseconds trap.
• Open Transport now installs the latest version of "classic" AppleTalk, so that if it is run on a machine that does not support Open Transport, "classic" AppleTalk will run instead. Using "remove" in the installer will now allow "classic" AppleTalk to run.
Backward-compatibility for AppleTalk
• MPP will no longer change a 0 network number to be "my" network number.
• Portions of MPP compatibility were made native in PowerPC.
• At boot time, AppleTalk now reads the preference file to determine if AppleTalk is ON or OFF, and overrides the value stored in parameter RAM.
Backward-compatibility for TCP/IP
• The .IPP driver will not force TCP/IP to load if a client makes the GetMyIPAddr() call.
• FreePPP has been added as a supported MDEV.
TCP/IP
• TCP/IP now supports hanging up and redialing SLIP and PPP connections without rebooting the machine.
AppleTalk
• Support was added for the XTI_SNDBUF, XTI_RCVBUF, XTI_SNDLOWAT and XTI_RCVLOWAT generic XTI options
• DDP will no longer change a 0 network number to "my" network number.
• On non-extended networks, if no router is present, change all network numbers to 0 before sending them.
• The NBP retry/interval algorithm was redone to allow a few more retries than previous versions.
Links
Other notes about this build.
ASLM 2.0
This build installs ASLM 2.0. If you currently have a debugging version of ASLM installed, installing the non-debug version of Open Transport will replace your debug version of ASLM with the non-debug version..
Macsbug messages
If you install the debug version of OpenTransport, there are many internal debugger breaks. You must have macsbug installed, or else if a debugger break occurs, you'll get the "bomb" box.
The Installer installs various Macsbug templates and DCMD's into your Debugger Prefs file. If you have Macsbug on the target machine, an Easy Install will automatically update the Debugger Prefs file. If you're using a newer Macsbug (6.5) which doesn't come with a Debugger Prefs file, the Installer will create a Debugger Prefs file.
There is mostly a pattern to the debugger messages that appear. Most messages have a leading 2-character code. The meanings are:
NB Nonfatal error. Dump all the registers and do a stack crawl and include the results in a bug report along with what you were doing at the time. Hit 'g' in Macsbug to continue. The machine should not crash, but it might hang.
FX Fatal error. An error that is probably fatal to the machine, but is cause by an external component, and not Open Transport itself.
NX Nonfatal error. An error occurred caused by an external component, and not Open Transport itself. Hit 'g' in Macsbug to continue. The machine should not crash, but it might hang.
UF User fatal err. A client of Open Transport did something wrong that is probably fatal. Reboot the machine.
UE User nonfatal error. A client of Open Transport did something wrong. Hit 'g' in Macsbug to continue. The machine should not crash or hang.
IE Informative error. An error occurred that should rarely happen. Hit 'g' in Macsbug to continue. The machine should not crash or hang.
IN Informative break. This is just an informational break. Hit 'g' in Macsbug to continue. The machine should not crash or hang.
Documentation
There is a "Document" folder which contains more documentation:
• Open Transport Client Note - A reference document for programmers wishing to write software using the Open Transport APIs.
• Open Tpt AppleTalk Dev Note - Material specific to AppleTalk.
• Open Tpt Serial Dev Note - Material specific to Serial endpoints.
• Open Tpt TCP/IP Dev Note - Material specific to TCP/IP.
All of these are preliminary. All of these will be worked over and turned into Apple DocViewer format documents for the final release of Open Transport 1.1.
The installer
The installer will Easy Install the Apple Shared Library Manager and Open Transport AppleTalk and TCP/IP version 1.0, as well as AppleTalk and MacTCP compatibility..
You can “undo” the AppleTalk compatibility installation by using the Network Software Installer 1.4.2 or later, and custom installing AppleTalk for System 7, Ignore any warnings it might give you about installing over a ‘newer’ AppleTalk.
This release also includes a version of MacTCP 3.0. To remove it, remove the TCP/IP Control Panel and reinstall the MacTCP control panel.
Debugger support
The installer will install Open Transport Debugger preferences into the DebuggerPrefs file in your System Folder, if you have one. These debugger prefs contain the ASLM debugger prefs plus Macsbug templates for virtually all structures used in the API. A Macbug dcmd is installed also that can display strings for error messages. For example, typing “OTErr -3158” will tell you what error number -3158 is.
Sample Code
There is a "Samples" folder which contains sample programs and source files.
All of the client samples are now Metrowerks projects (built with the Metrowerks IDE 1.3).
Earlier Release Notes
API changes since 1.0.5b2
• Many new utility APIs were moved into OpenTransport.h. These APIs are not strictly necessary to use Open Transport. They are utilities that are used by the implementation of Open Transport that you might find useful.
• Routines to directly manipulate streams were added to OpenTransport.h. These APIs do not have (and will never have) mixed-mode glue. They many only be used by native code, so applications that use these APIs should be FAT. The Open Tpt Client Deverloper note has NOT been updated yet with all of these APIs.
• Pascal header files are in better shape. They do not reflect any of the new native-only APIs.
• Some new APIs have been added to the InternetServices object to handle obtaining direct access to DNS records (see the OpenTptInternet.h header files). Documentation will be added to the Open Tpt TCP Dev. Note shortly.
• OTGetProviderPort was added to get the OTPortRef associated with a provider, if applicable.
• The APIs to the OTCompareAndSwap8, etc.. functions were changed to take a UInt32 so that the API works properly with Symantec and Metrowerks compilers.
• A new event, kOTNewPortRegistered, is now sent to clients who have register with Open Transport using the OTRegisterAsClient API. It is sent whenever a new port driver is registered with Open Transport.
• The no-copy receive API was made public - it consists of the constant kOTNetbufIsOTBufferStar, the OTBuffer and OTBufferInfo structures, and the OTReadBuffer and OTReleaseBuffer APIs. This API set will also work under Copland as a no-copy receive.
Bug Fixes since 1.0.5b2
General
• Fixed the timer APIs on PowerPC machines. These were not working correctly.
• When swapping stacks, the _StackSpace trap is now patched to correctly return the amount of remaining stack space. This fixes problems with a hang on the 660AV and 840AV machines when using ethernet.
• For transaction endpoints, T_REQUEST events could get lost while reading replies.
• Open Transport was not detecting callbacks from ADEVs, MDEVS, or the .DRVR shim at VBL time, causing problems with STREAM synchronization.
• Some race conditions were found under heavy stress in the endpoint APIs.
• Fixed a problem with "child" ports in the OTPortRecord. "Child" ports are now correctly returned.
• Added #pragma pointers_in_D0 for Metrowerks users in a few places where they were missed.
• According to the XTI specification, T_GODATA and T_GOEXDATA events are supposed to be higher priority than all the other events. Open Transport was modified to conform.
• OTResolveAddress returned a kOTNotSupported error if the underlying provider did not support OTGetProtAddress, instead of checking if the underlying provider supported OTResolveAddress.
• Fixed the prototypes for the t_unitrequest and t_unitreply functions in OpenTptXTI.h
• A kEFAULTErr is now returned if an asynchronous Open routine is invoked with a 0 for the OTNotifyProcPtr.
• Fixed a problem between Open Transport and VM at shutdown which could cause a crash.
• SndURequests that time out now return an ETIMEDOUT error instead of no error and no data.
• The T_ACCEPTCOMPLETE event was being sent to the wrong endpoint in the case where the accept was done on an alternate endpoint.
• ADSP now Accepts on an alternate endpoint that is bound. In prior versions, a crash would occur shortly after the Accept.
• Fixed a problem with the OTMemset API when compiled with Metrowerks. Using OTMemset would set a large amount of memory in this case, usually leading to a crash.
Backward-compatibility for AppleTalk
• Fixed some race conditions in the CloseSocket path that sometimes left endpoints open. This caused AppleTalk to eventually run out of sockets for clients that were using ATP's SendRequest API (the one that opens a new socket every time).
• Fixed a crash when disconnecting ARA.
• The ZIP calls now correctly return a kNoBridgeErr if no router is present. They used to return noErr, with no data in the reply buffer.
• In the Chooser, if we were booted with extension off, don't write PRAM. Otherwise, the next time we reboot, AppleTalk will still be off.
• GetAppleTalkInfo.SelfSend now reflects the actual self-send flag. It was always returning true before.
• Problems with Quickmail and other applications that do not give System Task time while talking on the network were alleviated.
• Several problems were fixed relating to flakiness of obtaining zone lists in various applications, including the Chooser.
• AppleTalk will no longer try to open and use ADEVs that are not version 3 or later. This caused crashes.
AppleTalk
• ADSP's Checksum option now defaults to false, as the documentation states.
• Made many improvements in the RTMP code. AppleTalk is now much more robust in the face of "bad" routers.
• Added some new notifications (Internet access available (Router came up), Internet access lost (All routers went down), and "Bad" router).
• If AppleTalk acquired a node with no router present, and a router subsequently came up that was compatible with our node address, AppleTalk was still unable to see off the cable properly because we did not add the appropriate multicast to the Ethernet driver.
• ADSP now returns an ETIMEDOUT error for a Connect request that timed out.
• Fixed a problem with ZIP returning zone lists, where sometimes zones were missing or duplicated.
• Fixed a problem where the ATP protocol was unloading while it was still in use.
• Fixed a problem in DDP if checksums were being used, where a packet with a checksum of 0xffff was being rejected.
• Fixed the stream-head receive and send flow-control sizes so they are 16K instead of 127 bytes!
• ADSP now honors the XTI_SNDBUF, XTI_RCVBUF, XTI_SNDLOWAT, and XTI_RCVLOWAT options.
Backward-compatibility for TCP/IP
• UDP now returns the actual interface MTU instead of just the default value.
• Support for the MXInfo and HInfo calls was added.
• In some cases, ASRs were called twice for stream termination. This caused problems for several MacTCP applications. This has been fixed.
• Fixed a problem where we died if no domain name was set up.
TCP/IP
• DHCP address leases are now working correctly.
• Worked around a problem with Windows NT DHCP servers where they do not conform to the relevant RFCs.
• Connect-by-name is now working again.
Links
• Alternate links (.ENET0, .TOKN0, .FDDI0) support is now working.
• When using the I_SetFraming IOCTL, the DRVR shim module now properly returns what the current framing value is.
• If a module did a freeb or freemsg at interrupt time, and a bufcall was pending, the bufcall was dispatched at interrupt time, causing chaos.
Changes since 1.0.5b2
General
• Updates were made to the Open Transport Developer Note and the Open Tpt Serial Developer Note.
• All of the samples are now supplied as Metrowerks projects. Since we have not been able to get PPC SIOWs working, this was the easiest way to supply working PPC samples. Since FAT programs are a good idea, we converted the 68K projects to Metrowerks as well. The Metrowerks projects use the Metrowerks IDE version 1.1 from the 9/5/95 Code Warrior Gold 7.0 Update.
• ASLM header files and libraries have been removed from the Open Transport sample builds. They are not necessary.
• A kEFAULTErr is returned if an async open is done without a notification proc parameter.
• kOTNotSupported is returned if an attempt is made to use a transaction API on a non-transaction endpoint.
• The "cookie" to a T_REPLY event is now the endpoint that the event occurred on. Also, T_REPLY events now act the same as all other data events (i.e. You only get 1 until you get a kOTNoDataErr or a kOTLookErr).
• Many new debugger breaks were added to the debug build to catch usage problems.
• The "0", "1", and "2" prefixes on debugger breaks have been updated to be a little more meaningful. See the section later in this document.
• Some header file changes were made to fix problems with Metrowerks support (#pragma pointers_in_d0, and allow Metrowerks to use SingleObject, since it now supports it).
• OTYieldPortRequest API was implemented.
• Footprint was significantly lowered if AppleTalk and TCP/IP are not being used.
• stropts.h is now supplied as a standard header file for Open Transport. This contains many streams equates for IOCTLs and other miscellaneous stream functions.
• OTGetTimeStamp is now very fast on PowerPC machines. Prior implementations used the microseconds trap, which is very slow. OTGetTimeStamp is now takes on the order of 400 nano-seconds instead of 20 microseconds.
Backward-compatibility for AppleTalk
• When promoting short DDP packets to long DDP packets, set the source network number to our network number rather than 0.
• Update the internal router address variables more often.
• Support for Alternate Ethernet devices was fixed.
• Fixed a problem with the Chooser displaying zone lists, where sometimes zones were missing or duplicated.
• Added a work-around for ill-behaved applications like Quickmail which do large amounts of ATP requests without ever yielding the CPU with SystemTask or GetNextEvent.
Backward-compatibility for TCP/IP
• Performance problems with SLIP and PPP MDEVs were alleviated somewhat. They were caused by sending data up to the client at interrupt time, which is not allowed by Open Transport.
• Several problems were fixed with changing the TCP/IP configuration while TCP applications were running.
TCP/IP
• Permit underscores in a domain-name component
* Added interface MTU and hardware address fields to InetInterfaceInfo structure. The structure was also modified to be more expandible in the future. It is not incompatible with Open Transport 1.0 -> 1.0.7 builds at this time. When Open Transport 2.0 for Copland ships, applications compiled with the OpenTptInternet.h from the 1.0 -> 1.0.7 SDKs will no longer work properly if they use this structure.
• The Control Panel now supports a "Use PPP Server" configuration method so that when using a PPP connection, the correct fields are greyed out for using the PPP server's configuration information.
• TCP/IP has been modifier to work with a Windows NT DHCP server (which does not conform to the RFCs for DHCP).
• We no longer send full-size DHCP or BOOTP packets. The packet length is set to the actual length of data in the DHCP or BOOTP request. This helps us work with several servers.
AppleTalk
• The OPT_SERVERSTATUS option for PAP now takes a non-terminated, non-pascal string (i.e. the length of the option defines the length of the string). In prior releases, it wanted a pascal string.
• Setting Self-Send now works exactly the way it worked under "Classic".
• Setting the OPT_SELFSEND option in DDP now works the way you would expect it to work. The previous implementation self-sent any broadcasts sent on the OPT_SELFSEND endpoint to whatever endpoint should receive it on the local node. The new implementation checks the destination endpoint of broadcast packets, and if OPT_SELFSEND is set, delivers the packet.
• AppleTalk now does a few more notifications for clients when things happen - "Router Up" and "Router down" notifications, as well as notification when all addresses are taken, or you've configured "fixed node" support and someone else has taken the node. All of these dialogs will auto-dismiss in 2 minutes if the user does not press "OK".
Links
• Many changes were made to the Serial implementation. Please read the Open Tpt Serial Developer Note, and examine the header file OpenTptSerial.h for details.
